<html>
  <head>
    <title>Using Xpo.UpdateSchema SchemaVersion</title>
    <link rel="stylesheet" type="text/css" href="../../styles/presentation.css" />
    <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
    <script type="text/javascript" src="../../scripts/EventUtilities.js"></script>
    <script type="text/javascript" src="../../scripts/SplitScreen.js"></script>
    <script type="text/javascript" src="../../scripts/Dropdown.js"></script>
    <script type="text/javascript" src="../../scripts/script_loc.js"></script>
    <script type="text/javascript" src="../../scripts/script_manifold.js"></script>
    <script type="text/javascript" src="../../scripts/script_feedBack.js"></script>
    <script type="text/javascript" src="../../scripts/CheckboxMenu.js"></script>
    <script type="text/javascript" src="../../scripts/CommonUtilities.js"></script>
  </head>
  <body>
    <input type="hidden" id="userDataCache" class="userDataStyle" />
    <input type="hidden" id="hiddenScrollOffset" />
    <img id="collapseImage" style="display:none; height:0; width:0;" src="../../icons/collapse_all.gif" title="Collapse image" />
    <img id="expandImage" style="display:none; height:0; width:0;" src="../../icons/expand_all.gif" title="Expand Image" />
    <img id="collapseAllImage" style="display:none; height:0; width:0;" src="../../icons/collapse_all.gif" />
    <img id="expandAllImage" style="display:none; height:0; width:0;" src="../../icons/expand_all.gif" />
    <img id="dropDownImage" style="display:none; height:0; width:0;" src="../../icon/dropdown.gif" />
    <img id="dropDownHoverImage" style="display:none; height:0; width:0;" src="../../icons/dropdownHover.gif" />
    <img id="copyImage" style="display:none; height:0; width:0;" src="../../icons/copycode.gif" title="Copy image" />
    <img id="copyHoverImage" style="display:none; height:0; width:0;" src="../../icons/copycodeHighlight.gif" title="CopyHover image" />
    <div id="header">
      <table id="topTable" cellspacing="0" cellpadding="0">
        <tr>
          <td>
            <span onclick="ExpandCollapseAll(toggleAllImage)" style="cursor:default;" onkeypress="ExpandCollapseAll_CheckKey(toggleAllImage, event)" tabindex="0">
              <img ID="toggleAllImage" class="toggleAll" src="../../icons/collapse_all.gif" />
              <label id="collapseAllLabel" for="toggleAllImage" style="display: none;">Collapse All</label>
              <label id="expandAllLabel" for="toggleAllImage" style="display: none;">Expand All</label>
            </span>
          </td>
        </tr>
      </table>
      <table id="bottomTable" cellpadding="0" cellspacing="0">
        <tr id="headerTableRow1">
          <td align="left">
            <span id="runningHeaderText">DevExpress Contrib</span>
          </td>
        </tr>
        <tr id="headerTableRow2">
          <td align="left">
            <span id="nsrTitle">
                  Using Xpo.UpdateSchema SchemaVersion
               </span>
          </td>
          <td align="center" style="width: 1px; padding: 0px">
            <img src="../../images/DevExContrib 32.png" alt="DevExpress Contrib" />
          </td>
        </tr>
        <tr id="headerTableRow3">
          <td align="left">
            <span id="headfb" class="feedbackhead" />
          </td>
        </tr>
      </table>
      <table id="gradientTable">
        <tr>
          <td class="nsrBottom" background="../../icons/gradient.gif" />
        </tr>
      </table>
    </div>
    <div id="mainSection">
      <div id="mainBody">
        <div class="Content">
          <p>As the data schema of an applicaion changes, the underlying program must check to see if
          the it is accessing the correct schema. If not, it could attempt to write to a field
          that has either been deleted, renamed, or not yet in the data store. One way to accomplish
          this is to keep a schema version in the data store and an expected schema version in the
          application. If they match, the application continues; if not, the application notifies the
          user and exits. SchemaVersion is incorporated in the Xpo.UpdateSchema to help manage this
          process.</p>
          <p>A class must implement the ISchemaVersion for Xpo.UpdateSchema to process the update.
          SchemaVersionBase, an abstract base class, provides most of the functionality required.
          SchemaVersionBase is a generic class so that a wide variety of types can be used for the
          version value. Testing has been done for both int and string types, but other simple types
          will most likely work as well. SchemaVersionBase also allows tracking of when the version
          was updated in the data store.</p>
          <p>First, create a XPObjectBase descendent to store the schema version. The SchemaVersionBase
          is designed to handle as a single record table with the schema version in a single field.
          If there are more than one records in this table an exception will be thrown.</p>
          <pre lang="cs" numberLines="true" outlining="true" title="Simple XPO class to store the schema version">
    /// <summary>
    /// DataStoreProperties is an XPO object to store 
    /// properties of the data store.
    /// </summary>
    public class DataStoreProperties : XPObject
    {
        private int schemaVersion;
        private DateTime schemaVersionUpdated;

        /// <summary>
        /// Initializes a new instance of the
        /// <see cref="DataStoreProperties"/> class.
        /// </summary>
        /// <param name="session">The session used to create the
        /// instance.</param>
        public DataStoreProperties(Session session)
            : base(session) { }

        /// <summary>
        /// Gets or sets the schema version.
        /// </summary>
        /// <value>The schema version.</value>
        public int SchemaVersion
        {
            get { return schemaVersion; }
            set { SetPropertyValue("SchemaVersion",
                ref schemaVersion, value); }
        }

        /// <summary>
        /// Gets or sets the DateTime the schema version
        /// was updated.
        /// </summary>
        /// <value>The DateTime the schema version was
        /// updated.</value>
        public DateTime SchemaVersionUpdated
        {
            get { return schemaVersionUpdated; }
            set { SetPropertyValue("SchemaVersionUpdated",
                ref schemaVersionUpdated, value); }
        }
    }</pre>
          <p>Next, create a descendent of SchemaVersionBase passing in the type of data to use the schema
          version. The following implementation stores the version as an integer.</p>
          <p>Example of an concrete ISchemaVersion implementation using SchemaVersionBase:</p>
          <pre lang="cs" numberLines="true" outlining="true" title="Simple SchemaVersion">
    /// <summary>
    /// The object used to update the schema version. Also
    /// provides information about the schema version.
    /// </summary>
    public class SchemaVersionInt : SchemaVersionBase<int>
    {
        /// <summary>
        /// Increment the requiredSchemaVersion value for
        /// each version of the schema
        /// </summary>
        private int requiredSchemaVersion = 1;

        /// <summary>
        /// Initializes a new instance of the
        /// <see cref="SchemaVersionInt"/> class.
        /// </summary>
        /// <param name="dataLayer">The XPO data layer to use
        /// when accessing the data store.</param>
        public SchemaVersionInt(IDataLayer dataLayer)
            : base(dataLayer) { }

        /// <summary>
        /// Gets the property name of the DateTime that the
        /// SchemaVersion was updated. If this is null or empty,
        /// no attempt will be made to store the updated time.
        /// </summary>
        /// <value>
        /// The property name of the DateTime that the
        /// SchemaVersion was updated.
        /// </value>
        public override string DateVersionUpdatedPropertyName
        { 
            get { return "SchemaVersionUpdated"; } 
        }

        /// <summary>
        /// Gets the name of the SchemaVersion property in the
        /// data store.
        /// </summary>
        /// <value>The name of the SchemaVersion property.</value>
        public override string VersionPropertyName
        {
            get { return "SchemaVersion"; }
        }

        /// <summary>
        /// Gets the type of the XPO object from the data store.
        /// This must be a descendant of XPObjectBase.
        /// </summary>
        /// <value>The type of the XPO object.</value>
        public override Type XpoObjectType
        {
            get { return typeof(DataStoreProperties); }
        }

        /// <summary>
        /// Gets the required schema version (as an object).
        /// This value is what the schema version should be
        /// for the current version of the application.
        /// </summary>
        /// <returns>
        /// The value (as an object) of the required data
        /// source schema version.
        /// </returns>
        public override int GetRequiredSchemaVersion()
        { 
            return requiredSchemaVersion;
        }
    }</pre>
          <p>In this example some key elements are:</p>
          <ul>
             <li>The property <code>XpoObjectType</code> is set to the <code>DataStoreProperties</code>
             class. This links this class with the SchemaVersion implementation.</li>
             <li>The property <code>VersionPropertyName</code> is set to the name of the property
             which holds the actual schema version; in this case <code>SchemaVersion</code>.</li>
             <li>Optionally the property which holds the <code>DateTime</code> that the SchemaVersion
             was updated can be set. In this case it is set to <code>SchemaVersionUpdated</code>.</li>
             <li>Finally, the actual value of the SchemaVersion is stored as a <code>const</code> in
             the field member <code>requiredSchemaVersion</code>. This value is manually changed
             each time the schema is updated on the users machine.</li>
          </ul>
          <p>To use the SchemaVersion instantiate the UpdateSchema object and pass in your ISchemaVersion
          implementation</p>
          
          <pre lang="cs" numberLines="true" outlining="true" title="Simple SchemaVersion">
    using(UpdateSchema updateSchema = new UpdateSchema("myConnectionString",
        new SchemaVersionInt()))
    {
    }</pre>
          <p>&nbsp;</p>
          <p>
            <a href="Task-Based Help.html">Back to task-based help.</a>
          </p>
        </div>
      </div>
      <div id="footer">
        <div class="footerLine">
          <img width="100%" height="3px" src="../../icons/footer.gif" title="Footer image" />
        </div>
        <p />
        <div id="DevLynxVersion">
           <p><small>v2009.0.3332.39062 (2009-02-14  21:42:04)</small></p>
        </div>
        <div id="DevLynxCopyright">
           <p>Copyright &copy; 2008-2009, DevLynx</p>
        </div>
      </div>
    </div>
  </body>
</html>
<!-- @SortOrder 3 -->
